KCG Lyrics

Purpose: build structured lyric briefs and AI-ready prompts for music generators (such as Suno or MiniMax) backed by AI (large-language-model) completions.

1. What the app does

KCG Lyrics collects your song concept (title, author, genre, atmosphere, mood, tempo, style, vocals, and structure), turns it into a strict bracketed template, and optionally submits the prompt to an AI model to return fully populated lyrics plus metadata. The app currently supports both Suno-oriented generation and MiniMax-oriented generation, each with its own metadata and lyrics formatting rules. Letting the AI draft everything is a good way to get a first draft that you can then modify as you please.

2. Requirements & first-time setup

• Keep an active internet connection; lyric generation and model continuations are online-only. All other features (templates, preset saves, copy/save/export) work offline.
  
• The app stores presets in JSON. If you use the quick-save buttons.

3. Main window tour

3.1 Project metadata (top left)

• Song Name: Appears in the [Title:] bracket and is used when suggesting filenames.
• Author: Used in the Suno [Author:] bracket and also reused by MiniMax as the [Name:] value. It is saved inside presets.
• Genre, Atmosphere, Mood: Free-text fields, each with an adjacent ••• helper button that opens curated pickers (see section 4).
• Tempo (BPM): Only digits are accepted. The field auto-sanitises and is emitted as [Tempo: ### bpm].
• Verse Count: Limited to 1–4 in the UI; internally the generator enforces at least two verses to keep the story balanced.
• Vocal Selector: The current options are Male, Female, Male/Female, Male Choir, Female Choir, and Full Choir. The selected label is injected into [Vocals:].

3.2 Creative detail (top right)

• Style: A multi-line field for instrumentation, production touches, era cues, etc. The default placeholder (“Folk, Whimsical…”) clears and switches back to black text the first time you click or type.
• Track Description: Longer prose describing the story, scene, or emotional arc. This paragraph becomes the [Track Description:] bracket and heavily steers the AI’s writing.
• Minimum Lines per Verse: Drop-down (2–10) telling the AI the minimum number of lines each section must contain.
• AI Provider: Choose Gemini or Groq. The selected provider is used by both the Suno and MiniMax generation buttons.

3.3 Structure controls (center band)

• Include checkboxes: Intro, Pre-Chorus, Chorus, Bridge, and Outro determine the exact order of the Lyrics section. Suno generation uses numbered verse headings such as [Verse 1], [Verse 2], blank lines between sections, and optionally [Final Chorus]. MiniMax generation uses its own allowed section tags and does not emit the Suno technical block.

3.4 Output & status (bottom half)

• Lyrics Results: A wide, scrollable editor that fills with either the AI response or the tags-only template. You can edit it before saving, copying, or pasting it elsewhere.
• Status bar: Updates for actions such as “Generating lyrics…”, “Generating MiniMax lyrics…”, “Presets saved.”, rate-limit retries, and validation problems. It stays enabled even while the rest of the window is temporarily disabled.
• Action buttons: Save Presets, Load Presets, Copy, Save (export to .txt), Generate Suno, Generate MiniMax, Tags Only, Clear Lyrics, and the ••• helpers for Genre/Mood/Style.

4. Helper palettes (Genre, Mood, Style)

Click any ••• button to open a picker window with curated drop-downs:

• Genre Helper: Tabs for Rock/Metal, Electronic & Dance, Pop/R&B/Soul, Hip-Hop/Rap, Country/Folk/Americana, Jazz/Blues, and Atmospheric/Soundtrack. Select a row, click Use to append it to the scratch pad, and hit Save to push the assembled string back into the main Genre field.
• Mood Helper: Lists covering High Energy, Dark & Serious, Positive & Playful, Atmospheric, Character-Driven, and Useful Modifiers. Works the same way as the Genre helper.
• Style Helper: Lets you mix vocal delivery ideas, instrumental arrangements, aesthetics & eras, rhythm & groove, and fantasy/RPG descriptors. Build a comma-separated description, press Save, and the text lands in the Style field.

Each helper resets its scratch text when you cancel or save, so you always start fresh.

5. Presets and project management

• Save Presets: Opens a Save dialog (default suggestion: “Lyrics - Preset.preset”). Entries are stored as JSON containing every field, drop-down choice, and structure checkbox. The extension .preset is accepted.
• Load Presets: Opens an existing preset and repopulates all fields. Invalid or empty files prompt a status message rather than overwriting your work.
• Quick defaults: Use Edit → Claer All to revert to the initial placeholder, reset numeric fields, re-enable every structure checkbox, and set the drop-down defaults (AI Provider = Gemini, Vocals = Male, Min Lines = 8).

6. Generating lyrics with AI

1. Fill in the metadata, creative, and structural panels.
2. (Optional) Use the helper palettes to build Genre/Mood/Style strings.
3. Confirm the Status bar does not show outstanding errors and that you are online.
4. Click Generate Suno or Generate MiniMax.
5. While the request is running, the app disables the window controls and leaves only the Status label active. This same temporary lock is used during Tags Only generation as well.
6. Generate Suno builds a Suno-oriented prompt with a metadata header containing [Title:], [Author:], [Genre:], [Atmosphere:], [Mood:], [Tempo:], [Time Signature:], [Key:], [Style:], [Vocals:], [Vocal Textures:], [Verses:], and [Min Lines Per Verse:], followed by the Lyrics section and Suno technical block.
7. Generate MiniMax builds a MiniMax-oriented prompt with a metadata header containing [Title:], [Name:], [Genre:], [Atmosphere:], [Mood:], [Tempo:], [Time Signature:], [Key:], [Style:], [Vocals:], [Vocal Textures:], [Verses:], and [Min Lines Per Verse:]. After Lyrics / ====== and one blank line, the lyrics begin immediately with MiniMax-approved section tags only. MiniMax also explicitly allows quoted phonetic vocal lines such as "la, la, la, la..." when humming or chanting is desired.
8. The AI receives the request. If the API returns a rate-limit error, the app waits five seconds and retries automatically up to six times.
9. When a response lands, KCG Lyrics validates required brackets, balanced markers, required sections, section-tag rules, and the Lyrics divider. If anything is missing, the app can request up to eight continuation attempts before stopping.
10. Once validation passes, the status reads that lyrics were generated, all controls re-enable, and the main metadata fields are updated to match the returned metadata: Song Name, Genre, Atmosphere, Mood, Tempo, Verse Count, Style, and Track Description.

7. Tags-only workflow

Click Tags Only to build the entire bracketed template without contacting the AI. This is ideal when you want to paste the framework directly into another AI yourself or write the lyrics yourself. The template contains:

• The Suno metadata block in the mandated order, including [Time Signature:], [Key:], [Vocal Textures:], and empty placeholders for [Album Art Prompt:] and [Hook:].
• A Lyrics heading, the ====== divider, and a technical block (Natural Voices, Key, BPM, Time Signature).
• The exact Suno section list built from your verse count and Include checkboxes, with blank lines between each section tag.

8. Exporting results

• Copy: Places the entire Lyrics Results text on the clipboard.
• Save: Opens a Save dialog. After Suno generation the suggested filename is “Song Name - Suno - Lyrics.txt”. After MiniMax generation the suggested filename is “Song Name - MiniMax - Lyrics.txt”. The exported file is plain UTF-8 text suitable for any text document editor.
• Status log: The status bar records where files were saved, making it easy to open the folder afterwards.

9. Menus & shortcuts

• File → Load/Save Presets: Same as the toolbar buttons.
• Edit menu: Standard Undo/Cut/Copy/Paste/Clear operations plus Claer All (see section 5). Keyboard shortcuts follow your OS conventions (Cmd on macOS, Ctrl on Windows/Linux).
• Help → About / License: Opens the About splash and license agreement windows.

10. Troubleshooting & best practices

• Rate limits: The app automatically retries after five seconds and currently allows up to six retry attempts before stopping.
• Incomplete responses: The app can request up to eight continuation attempts before surfacing the best text received and telling you what was still missing.
• Placeholder Style text: Click the Style box once before typing so the greyed-out hint example clears.
• Verse count and structure: Because the minimum enforced verse count is two, a single-verse song will still be generated with two verses. Reduce clutter by unchecking extra sections or editing the output manually.
• Neon safety: The helper prevents the word “neon” from being added unless you explicitly typed it, which keeps prompts literal when you are writing for folk/acoustic pieces.

11. Additional references

• How to Use AI Lyric Metatags (Master Guide): Included with the project as How to Use AI Lyric Metatags.md and related HTML. Read it to learn the meaning of the AI music tags used in the Suno-oriented workflow.
• How to Use Suno (HTML): A richer, formatted walkthrough located at How_to_Use_Suno.html.
• User Documentation: This file (User_Documentation.html) lives alongside the project.

If you need more help, open the Help menu or contact Kevin Cary-Grimm with your preset file and a screenshot of the status bar so they can reproduce the issue.